
package org.apache.mina.common;

import java.io.IOException;
import java.net.SocketAddress;

/**
 * Accepts incoming connection, communicates with clients, and fires events to
 * {@link IoHandler}s.
 * <p>
 * Please refer to <a href=
 * "../../../../../xref-examples/org/apache/mina/examples/echoserver/Main.html"
 * >EchoServer</a> example.
 * <p>
 * You should bind to the desired socket address to accept incoming connections,
 * and then events for incoming connections will be sent to the specified
 * default {@link IoHandler}.
 * <p>
 * Threads accept incoming connections start automatically when
 * {@link #bind(SocketAddress, IoHandler)} is invoked, and stop when all
 * addresses are unbound.
 * 
 * 接受进来的连接，与客户端通讯，并触发事件到IoHandler。
 * 
 * 你应该绑定到被请求的socket地址，用来接受进来的连接，然后进来的连接的事件将会被发送到指定的IoHandler。
 * 
 * 当bind(SocketAddress, IoHandler)方法被调用时，线程自动启动用来接受进来的连接。当所有地址解除绑定时，线程将会停止。
 */
public interface IoAcceptor extends IoService {
    /**
     * Binds to the specified <code>address</code> and handles incoming
     * connections with the specified <code>handler</code>.
     * 
     * 绑定到指定的address，并用指定的IoHandler用来处理进来的连接。
     */
    void bind(SocketAddress address, IoHandler handler) throws IOException;

    /**
     * Binds to the specified <code>address</code> and handles incoming
     * connections with the specified <code>handler</code>.
     * 
     * 绑定到指定的address，并用指定的IoHandler用来处理进来的连接。
     * 
     * @param config
     *            the configuration
     * @throws IOException
     *             if failed to bind
     * 
     */
    void bind(SocketAddress address, IoHandler handler, IoServiceConfig config)
            throws IOException;

    /**
     * Unbinds from the specified <code>address</code> and disconnects all
     * clients connected there.
     * 
     * 解绑定指定的address，并将连接到该地址的客户端断开连接。
     */
    void unbind(SocketAddress address);

    /**
     * Unbinds all addresses which were bound by this acceptor.
     * 
     * 将所有绑室此acceptor的地址解绑定。
     */
    void unbindAll();

    /**
     * (Optional) Returns an {@link IoSession} that is bound to the specified
     * <tt>localAddress</tt> and <tt>remoteAddress</tt> which reuses the
     * <tt>localAddress</tt> that is already bound by {@link IoAcceptor} via
     * {@link #bind(SocketAddress, IoHandler)}.
     * <p>
     * This operation is optional. Please throw
     * {@link UnsupportedOperationException} if the transport type doesn't
     * support this operation. This operation is usually implemented for
     * connectionless transport types.
     * 
     * 
     * 返回一个IoSession，该session绑室指定的localAddress和remoteAddress。
     * 其中localAddress已经通过bind()方法绑定到此IoAcceptor对象。
     * 可选的方法，如果不实现该方法，将抛出UnsupportedOperationException异常。
     * 
     * @throws UnsupportedOperationException
     *             if this operation is not supported
     * @throws IllegalArgumentException
     *             if the specified <tt>localAddress</tt> is not bound yet. (see
     *             {@link #bind(SocketAddress, IoHandler)})
     * 
     */
    IoSession newSession(SocketAddress remoteAddress, SocketAddress localAddress);
}